home *** CD-ROM | disk | FTP | other *** search
/ Amiga Games: Greatest Hits 1996 / Amiga Games: Greatest Hits 1996.iso / archive / userbox / publicdomain / yagin.lha / YAGIN / Archives / socket_lib12.lha / socket.doc < prev    next >
Text File  |  1994-09-27  |  20KB  |  501 lines
  1.  
  2.                S O C K E T . L I B R A R Y - E M U L A T I O N
  3.                ===============================================
  4.  
  5. [  No, it's not one of these fancy AmigaGuide® documents.  Consider me one of
  6. these  old  fashioned  Unix  hackers,  which prefer writing code over writing
  7. documentation ]
  8.  
  9.  
  10. COPYRIGHT
  11.  
  12. This program is © 1993, 1994 by Henning Schmiedehausen.  All rights reserved.
  13.  
  14. This  program is Chocolade-Ware.  If you find it useful, feel free to send me
  15. a bar of chocolade or two (I like 'Milka Vollmilch').
  16.  
  17. I  will  not  distribute  the  source  of  this software at the current time,
  18. because  it  is  programmed  after  a  documentation  file,  which  is (C) by
  19. Commodore 1990, 1991, 1992 and still under non-disclosure.
  20.  
  21. I  can  tell  you  something  about the compatibility, but if you need *real*
  22. documentation,  it  is  necessary,  that  you  become  an  official Commodore
  23. Developer  and  sign  a  non-disclosure  agreement  with Commodore to receive
  24. autodocs on the AS225R2 package.
  25.  
  26. The  whole  program  and  all  files  in  this  archive  are (C) 1994 Henning
  27. Schmiedehausen.  All rights reserved.  This is freely distributable software,
  28. not Public Domain.
  29.  
  30.  
  31. AUTHOR
  32.  
  33. Henning Schmiedehausen
  34. Marquardsenstraße 3
  35. D-91054 Erlangen
  36. Germany
  37.  
  38. EMail:
  39. barnard@forge.franken.de
  40.  
  41. The program was written with CygnusED 3.5 and compiled with SAS C V 6.3 using
  42. the  3.1  AUK,  the  AmiTCP  includes  and the AS225R2 developer kit.  
  43. (I'm an official Commodore developer, so this is legal)
  44.  
  45. It  was  tested and debugged on two A3000 with AmigaOS 3.1 using a Picasso II
  46. Gfx Board, some Ariadne Ethernet Boards and AmiTCP 2.3.
  47.  
  48.  
  49. DISTRIBUTION
  50.  
  51. This  program  may be copied and freely distributed via electronic media such
  52. as  Mailboxes,  Internet  and  Usenet,  as long as the integrity of the whole
  53. archive is kept and this README is included without any changes.
  54.  
  55. You  are  allowed  to re-pack this archive with other compressing methods, as
  56. long as all files are kept unmodified in such a new archive.
  57.  
  58. You  are  not  allowed to add any files to the archive, delete any files from
  59. the archive or modify any of the files in the archive.
  60.  
  61. Especially  BBS  sysops  are  not  allowed  to  add any advertisments to this
  62. archive or to any of the files of the archive.
  63.  
  64. If you find any archive with such BBS ads, please send them to me.
  65.  
  66. This  software  may  only  be included in freely distributable Disk and CDROM
  67. libraries  with  the  written  permission  of  the author.  If you want to be
  68. added, please send me a stamped, self addressed envelope.
  69.  
  70. This permission is herewith given for
  71.  
  72. The Fred Fish Library (including the CD ROM releases)
  73. The Fred Fish Library on CD ROM
  74. SAAR AG PD Series
  75. The AmiNet CD ROM's from Walnut Creek
  76.  
  77.  
  78. DISCLAIMER
  79.  
  80. The following disclaimer is for the program called 'socket.library', from now
  81. on called 'program'.
  82.  
  83. I  hereby  reject  any  liability  or  responsibility  for these or any other
  84. consequences from the use of 'program' whatsoever.  This includes, but is not
  85. limited  to,  damage to your equipment, to your data, personal injuries, loss
  86. of money, loss of hair, loss of concience or any other kinds of side effects.
  87.  
  88. Although  'program'  has been tested thoroughly on some different machines, I
  89. cannot rule out the possibility that 'program'
  90.  
  91.    * is somehow incompatible to your equipment
  92.  
  93.    * has bugs that show up on your equipment
  94.  
  95.    * does not do what it is supposed to do on your equipment
  96.  
  97. It  is  your  responsiblity  to  take  any  precautions  necessary to protect
  98. yourself  from these or any other effects.  I explicitly reject any liability
  99. or responsibility from the consequences of you using 'program'.
  100.  
  101. And  for  our  german  friends,  who feel the urge to express certain politic
  102. statements with the distribution of their software:
  103.  
  104. Hiermit  sei  es ausdrücklich gestattet diese Software zu all jenen Dingen zu
  105. gebrauchen,  die kleinkarierte Dogmatiker ihren potentiellen Kunden verbieten
  106. wollen,   also   beispielsweise   die   Übertragung   der  Wasserstoffbomben-
  107. konstruktionsunterlagen an Killer-Mutanten vom Mars oder der Verkauf an Arme,
  108. die   der   kostenfreien  Beschaffungsmöglichkeiten  von  frei  vertreibbarer
  109. Software unkundig sind.  Dennoch wird um Zusendung von Schokolade gebeten.
  110.  
  111.  
  112. THANKS
  113.  
  114. * The AmiTCP group, consisting of
  115.         Tomi Ollila    <Tomi.Ollila@cs.hut.fi>
  116.         Pekka Pessi    <Pekka.Pessi@hut.fi>
  117.         Markus Peuhkuri    <Markus.Peuhkuri@hut.fi>
  118.         Jarno Rajahalme    <Jarno.Rajahalme@hut.fi>
  119.  
  120.   for bringing such a superb program like AmiTCP to the Amiga community.
  121.  
  122.   ... and for rolling the ball to me.
  123.  
  124. *  All the folks at the Commodore developer support for providing us with at
  125.    least a little information.
  126.  
  127. *  Ken Dyke and Randell Jesup for answering lots of silly questions.
  128.  
  129. *  Kristin for just being there.
  130.  
  131. *  David Swasbrook, Author of 'SwazInfo', where I stole the upper part of the
  132.    Disclaimer.
  133.  
  134. *  Lutz Vieweg; I stole the german 'Disclaimer' from his TWC archive :-)
  135.    (You'll get a chocolade next time you come to an Amiga meeting.  :-)
  136.  
  137. *  My Beta-Testers:
  138.       The AmiTCP group  -    amitcp-group@hut.fi
  139.       Markus Illenseer  -    markus@techfak.uni-bielefeld.de
  140.       Hakan Tandogan    -    hakan@kahalo.franken.de
  141.       Rudolf Neuhaus    -    rudy@dorn.ruhr.de
  142.       Thomas Kroener    -    kroener@mercury.saar.de 
  143.       Carsten Heyl      -    ch@irb.informatik.uni-dortmund.de
  144.       Matthias Scheler  -    tron@lyssa.pb.owl.de
  145.       Timo Rossi        -    trossi@tukki.jyu.fi
  146.       Cor Bosman        -    cor@hacktic.nl
  147.       Chris Mattingly   -    ozzy@catt.ncsu.edu
  148.       Michael B. Smith  -    mbs@adastra.cvl.va.us
  149.       Michael C. Taylor -    MCTAYLOR@mta.ca
  150.       Ty Sarna          -    tsarna@endicor.com
  151.       Dale Luck         -    dale@ntg.com
  152.       Mike Meyer        -    mwm@contessa.phone.net 
  153.  
  154. *  The nice people who live in the appartment on the floor above and tolerate
  155.    programming sessions till 5am without knocking on my door.
  156.  
  157. *  All the folks from #amigager, who much too often successfully distracted me
  158.    from my real work..
  159.  
  160. *  Tron, Top & Hakan for the chocolate.
  161.  
  162.  
  163. NEEDED EQUIPMENT
  164.  
  165. - Amiga computer, running AmigaOS 2.04 or beyond.
  166.   2.1 or better is recommended (see get_tz)
  167.  
  168. - AmiTCP installed; V 2.3 or beyond is recommended
  169.  
  170. - Some basic grip to TCP/IP software
  171.  
  172.  
  173. WHAT IS IT FOR
  174.  
  175. Currently,  networking  on the Amiga is in a terrible situation:
  176.  
  177. There is an official TCP/IP package from Commodore, called AS225R2, but it is
  178. not  released yet and only available to official Commodore Devlopers.  Due to
  179. the situation of Commodore, I do not expect them to release it any time soon.
  180. This  package  has  the  advantage of containing well ported clients and some
  181. servers, including an NFS Server for the Amiga.  Unfortunately, almost nobody
  182. has it.
  183.  
  184. Then there is AmiTCP.  Brand new, a little rugged, but a great effort, Freely
  185. distributable and comes with full source.  Every programmers dream.
  186.  
  187. You can guess, what happened:  Both protocol stacks come with different APIs.
  188. Programs, which run under AmiTCP will not work under AS225 and vice versa.
  189.  
  190. Most  of the people who develop TCP/IP software for the Amiga, write (in this
  191. desparate situation) their software for both both protocol stacks and put for
  192. every program two archives on the ftp sites.
  193.  
  194. I  always  thought,  that  this  is  the  wrong  approach  to the problem.  I
  195. investigated  both possibilities to unify the APIs of AmiTCP and AS225, but I
  196. always thought that the AmiTCP API is in many way superior to AS225 API.
  197.  
  198. Due to some problems (I will tell you later), only one approach is possible:
  199.  
  200. Putting  an AS225R2 compatible socket.library on top of AmiTCP.
  201.  
  202. This  library enables, most of the AS225 client programs to run under AmiTCP,
  203. and make the transition from AS225 to AmiTCP as smooth as possible.
  204.  
  205. I tried the following client programs for AS225:
  206.  
  207. Original-Commodore:
  208.  
  209. finger         - works
  210. ftp            - works with KLUDGE switch (see below)
  211. nfsmgr         - works
  212. showmount      - works
  213. ping           - works
  214. rsh            - works
  215. rlogin         - works
  216.  
  217. nfsd           - works
  218.  
  219. rcp            - this program is linked with the socket-link library. It will
  220.                  never run. No chance to emulate.
  221.  
  222. Shell-Telnet   from Matthias Scheler: works
  223. AmigaIrc Alpha from Petra Zeidler:    works
  224.  
  225.  
  226. INSTALLATION
  227.  
  228. Make a directory called 'AmiTCP:LIBS'
  229. Copy the socket.library file to this directory.
  230.  
  231.  
  232. VERSION
  233.  
  234. Don't  be  confused  by the version of the socket.library.  Many of the older
  235. AS225 programs rely on a socket.library V 4.x.  So the library adds itself as
  236. 'socket.library  V  4.4' to the system.  You can find out the real version of
  237. the socket.library mit 'version file libs:socket.library'.
  238.  
  239.  
  240. USAGE
  241.  
  242. AmiTCP *must* be started, before any program can open socket.library.
  243.  
  244. Most  of  the AS225 programs open 'Inet:libs/socket.library'.  To work around
  245. this,  you must load the library into memory before using it (or the programs
  246. will  say 'cannot open socket.library').  There is a 'loadlib' tool provided,
  247. which can do this for you.
  248. You  use it as 'loadlib AmiTCP:libs/socket.library' Best thing will be to put
  249. it into your AmiTCP:bin/startnet file.
  250.  
  251. You  can  also  make an assign 'ASSIGN INET:  AmiTCP:'.  This will solve your
  252. problem without any library-loading.  You have one more assign, though.
  253.  
  254.  
  255. CONFIG FILES
  256.  
  257. The library needs two things:
  258.  
  259. -  The  hostname  of  your  Amiga must be set in ENV:HOSTNAME.  It can have a
  260.    domain,  which  is  cut  off.   e.g.   setenv  HOSTNAME  forge (this is my
  261.    hostname) or setenv HOSTNAME forge.franken.de
  262.  
  263. -  You  need  a  environment  variable  called  'ENV:SOCKETCONFIG'  with  the
  264.    following options:
  265.  
  266.    UID/N/A    - User ID of the user at the console
  267.  
  268.    GID/N/A    - Group ID of the user at the console
  269.  
  270.    USER/A     - Name of the user at the console
  271.  
  272.    DOMAIN/A   - Domain of your Amiga *without* leading dot
  273.  
  274.    UMASK/A/N  - Umask for NFS writes
  275.  
  276.    KLUDGE/S   - see below
  277.  
  278.    An example is:
  279.  
  280.    setenv SOCKETCONFIG "UID=200 GID=200 USER=barnard DOMAIN=franken.de UMASK=002"
  281.  
  282.  
  283. Well, then you should be ready to go.
  284.  
  285.  
  286. COMPATIBILITY (that's what you've waited for)
  287.  
  288. Well,  at  first I thought of this whole project as impossible.  That's why I
  289. put  it back again and again (I first had the thought right after the release
  290. of AmiTCP 1.0)
  291.  
  292. But   then   again   I   looked   at   it   and   some   UseNet  Articles  in
  293. comp.sys.amiga.datacomm  seemed to imply that it *can* be done.  AS225 is, as
  294. far  as  I  know,  derived from the BSD 4.3 Networking code, while the AmiTCP
  295. comes  from the Mach BSD port of the Berkley Net/2 release.  So, they are not
  296. too different from each other.  After looking at the fuction calls, it seemed
  297. to possible.
  298.  
  299.  
  300. COMPATIBILITY ISSUES
  301.  
  302. - library calls
  303.  
  304.   - The following calls have been ported and should work without any drawbacks:
  305.  
  306.     setup_sockets, cleanup_sockets, socket, s_close, s_getsignal,
  307.     gethostbyname, gethostbyaddr, inet_addr, inet_makeaddr, inet_lnaof,
  308.     inet_netof, inet_network, inet_ntoa, listen, recv, send, shutdown,
  309.     setsockopt, getsockopt, getnetbyaddr, getnetbyname, getprotobyname,
  310.     getprotobynumber, getservbyname, getservbyport, getpwuid, getpwnam,
  311.     getpeername, getsockname, gethostname, s_syslog, rcmd
  312.  
  313.   - strerror
  314.       AmiTCP  does  not  contain a system call for returning an error string.
  315.       (Shame  on  you  folks.   This increases every AmiTCP user program by 2
  316.       KBytes  for  useless  strings)  I  took  the  strings  from  the  AS225
  317.       sys/errno.h file.
  318.  
  319.   - getuid, getgid, getlogin, getdomainname, getumask, umask
  320.       AmiTCP has (to my knowledge) no concept of the user at the console. It
  321.       seems to be always the root user. These calls return the contents of
  322.       the ENV:SOCKETCONFIG file:
  323.  
  324.       getuid:        UID
  325.       getgid:        GID
  326.       getlogin:      USER
  327.       getdomainname: DOMAIN
  328.       getumask:      UMASK
  329.  
  330.   - getgroups
  331.       Gets only the primary group of the user.
  332.  
  333.   - get_tz
  334.       AmiTCP has some nice code featuring locale.library to get the offset.
  335.       I use it also for get_tz. AS225 just reads it from its config file.
  336.  
  337.   - select, selectwait
  338.       NUMFD is bigger for AS225 than for AmiTCP.  AS225 uses fd_sets with 128
  339.       Bits,  for FD masks while AmiTCP uses fd_sets, which have only 64 Bits.
  340.       This seems not much of a problem for me, because most programs won't us
  341.       that  much sockets, but you have been noticed.  If you think, that this
  342.       is a problem, recompile AmiTCP with 128 Bits for FD_SETSIZE.
  343.  
  344.       NOTE:   I  was  pretty impressed that AS225 identically to AmiTCP has a
  345.       call   like  'selectwait  /  WaitSelect',  which  is  not  only  almost
  346.       identically named but has almost the same parameters.  The AmiTCP folks
  347.       say,  that  they haven't seen the AS225 API before releasing AmiTCP, so
  348.       it seems to be a logic extension to the BSD stuff. I haven't tested it
  349.       under all circumstances, but it seems to work
  350.  
  351.   - accept, bind, connect, recvfrom, sendto
  352.       AmiTCP  has  a  different  idea  than AS225 of what a 'struct sockaddr'
  353.       should  be.  (This not the fault of the AmiTCP folks, but of the people
  354.       who  moved 4.3 into the Net/2 Release.  :-) ) I wrote a wrapper for all
  355.       These  functions,  it should work, but I do not claim responsibility if
  356.       this is one reason for failure.
  357.  
  358.   - s_ioctl
  359.       The first tough one. AmiTCP has total different codes for its ioctls.
  360.       I've supported only the following IOCTL's:
  361.  
  362.        SIOCATMARK, FIONBIO, FIONREAD, FIOASYNC, SIOCSPGRP, SIOCGPGRP
  363.  
  364.       Of course this effectivly keeps almost everything not related to
  365.       sockets from running. But then again, these are only:
  366.  
  367.         SIOCADDRT, SIOCDELRT - for route support, so the AS225
  368.         'route' command and the 'routed' will not work
  369.  
  370.         [NOTE: Somebody told me, that the routed *does* run, but is not
  371.         able to add new routes, which it gets from other routed's via RIP
  372.         into the AmiTCP route tables. But it should be able to broadcast
  373.         its known routes to other machines on the net. I didn't test it
  374.         but IMHO it is possible. I have neither connection to a bigger 
  375.         public network nor the possibility to test this in deep. ]
  376.  
  377.         SIOCSIFADDR, SIOCGIFADDR, SIOCSIFDSTADDR, SIOCGIFDSTADDR,
  378.         SIOCSIFFLAGS, SIOCGIFFLAGS, SIOCGIFBRDADDR, SIOCSIFBRDADDR,
  379.         SIOCGIFNETMASK, SIOCSIFNETMASK, SIOCGIFMETRIC, SIOCSIFMETRIC,
  380.         SIOCGIFCONF
  381.  
  382.         this keeps also the 'ifconfig' and 'netstat' commands from working
  383.  
  384.         SIOCSARP, SIOCGARP, SIOCDARP
  385.  
  386.         this kills the 'arp' command.
  387.  
  388.         NOTE:   Even  if  you  implement the ioctl's you won't be able to run
  389.         ifconfig from AS225, because AmiTCP uses different (IMHO silly) names
  390.         for  the  interfaces.  Why didn't they omit the '.device'?  'ifconfig
  391.         slip/0'  would  be  sooo  nice.   :-)  (Consider  this an enhancement
  392.         request)
  393.  
  394.         NOTE2:   Most  of  the ioctls are also there in AmiTCP.  However, the
  395.         structures  used in AmiTCP and AS225 are *very* different (there seem
  396.         to  be heavy changes in the 4.3->Net/2 transition).  I consider these
  397.         ioctls less important, so I dropped this from this release.
  398.  
  399.         SIOCSSLIPDEV, SIOCSIFMTU, SIOCGIFMTU
  400.  
  401.         These ioctls() are missing completly, they're not in AmiTCP.
  402.  
  403.   - getpwent, endpwent, setpwent
  404.       They're in there. However, I do not recommend to use them.
  405.  
  406.   - s_dev_list
  407.       This  is  a  funny  one.  AS225 uses this one to map the list of socket
  408.       descriptors to the list of file descriptors of SAS C 5.  This call does
  409.       no  longer  work  with  SAS C 6, because there this list is no longer a
  410.       static  array but a linked list.  I could have skipped this call if not
  411.       for the 'ftp' program:
  412.  
  413.       If  s_dev_list()  does  nothing, the AS225 'ftp' client no longer works
  414.       correct.  You won't see any output from it.  It seems to me, that some-
  415.       how, 'ftp' uses this file<->socket relation; maybe the programmer wrote
  416.       a wrapper to use sockets as files.  I don't know.
  417.  
  418.       This is, where the 'KLUDGE' switch from the config file comes in:
  419.       If you enter 'KLUDGE' in the config-file, socket.library will claim the
  420.       first  eight  sockets  of  every open library base and return no socket
  421.       numbers below '8'.  Then 'ftp' works.  Don't ask me, why, though.  :-)
  422.  
  423.       I don't really like this kludge; I don't think, any of the user supplied
  424.       programs for AS225 will ever make real use of this call, especially not
  425.       under  SAS  C  6.x.   So  you  may  need this kludge only for the 'ftp'
  426.       client.  If you will not use it, don't set it.
  427.  
  428.   -  setnetent,  endnetent, getnetent, setprotoent, endprotoent, getprotoent,
  429.      setservent, endservent, getservent, sethostent, endhostent, gethostent
  430.  
  431.       These are internal calls to access various files (networks, protocols,
  432.       services, hosts).  Will not be supported.  Don't use them.
  433.  
  434.   -  reconfig
  435.       Not supported. Should be possible via sending an ARexx Command to the
  436.       stack.  I can't think of an application to use this.
  437.  
  438.   -  s_release, s_inherit
  439.       These are the bad guys.  Not supported, I doubt that they ever will be.
  440.       (I  have no idea, how) This prevents *every* AS225 server from running,
  441.       because  AmiTCP  uses  a  different (BETTER!) protocol to give a socket
  442.       from inetd to a started server.
  443.  
  444.   -  recvmsg, sendmsg
  445.       Advanced send() and recv(). Should be implementable without too much
  446.       hassle, but I didn't need it.... :-)
  447.  
  448. - structures
  449.  
  450.   Well, most of the structures needed are identical (Thank god) or don't care
  451.   (sockets).   I had to deal explicitly with two:  passwd and sockaddr.
  452.   Both wrappers should work fine.
  453.  
  454. CONCLUSION
  455.  
  456. Well,  so  much for that.  This library now pretty much fills *my* needs.  If
  457. you  have any ideas or if you find bugs, tell me.  My EMail address is listed
  458. above.   I  will  not  implement  anything  new until I need it or get public
  459. demand.   If find programs that run (...that not run) which are not mentioned
  460. in the list above, please send me a mail.
  461.  
  462. BTW: The writing of a bsdsocket.library to sit on AS225:
  463.  
  464. Sorry, but thats IMHO not possible. Several reasons:
  465.  
  466. a)  The  brain  damaged way, AmiTCP handles its Password file.  The calls for
  467.     that  (along  with  the  group  stuff  and  gethostname)  are in a *LINK*
  468.     library.   Pretty  much  all  user programs, who need this stuff carry it
  469.     around in its binary.  So you can't write a library to redirect.  I hope,
  470.     this will be changed in AmiTCP 3.0 or beyond.  (But I think, it's already
  471.     too late.  :( )
  472.  
  473. b)  The missing strerror() call. Same as above
  474.  
  475. c)  Totally different signal structure. AS225 allocates its signals and gives
  476.     the user the ability to query them via getsignal().
  477.     AmiTCP just offers a call to set complete masks for the signals. To come
  478.     from AmiTCP to AS225 is easy (allocate two signals in the library base,
  479.     give them to AmiTCP and return them on getsignal()). But how to emulate
  480.     the setting of masks?
  481.  
  482. ENHANCEMENT REQUEST (Not really...  :-) )
  483.  
  484. I  desperatly  need  an  SMTP  and an NNTP client and a SMTPd and a NNTPd for
  485. AmiTCP.   Is  there nobody out there, who will write this stuff?  I'm willing
  486. to Beta-test...
  487.  
  488.  
  489. HISTORY
  490.  
  491.  7. 1. 94  - V 1.0ß - First Beta release (including a release for the KA '94 
  492.                                           German Amiga Users Meeting)
  493.  
  494. 20. 2. 94  - V 1.0  - First public release
  495.  
  496. 10. 9. 94  - V 1.1  - Minimal bug in _UserLibInit fixed; (mlelstv)
  497.  
  498. 24. 9. 94  - V 1.2  - Added ignoring of Domain in HOSTNAME
  499.  
  500. -- © Henning Schmiedehausen 1994 - All rights reserved
  501.